Archive Service

1. Service Overview

dmss-archive-services is the DMSS storage abstraction layer. It provides a uniform API for document create/read/update/delete/search while routing requests to configured archive backends.

It also manages failover and delayed synchronization when primary backends are unavailable.

2. Scope and Responsibilities

Primary responsibilities:

• Create, update, version, download, search, and delete documents via a unified REST API.
• Resolve documentType -> archive connection routing using category mappings.
• Persist service-level document identity metadata (optional DB-backed mapping).
• Support fallback/pipeline writes and later synchronization to target archive.
• Expose metadata/object/archive information and external authentication helpers.

Out of scope:

• Digital signing orchestration (handled by container/signature service).
• Cryptographic signature generation and session state orchestration.

3. Architecture

Runtime building blocks:

• API layer: v1 and v2 controllers under controllers/api.
• Core orchestration: ArchiveService.
• Connector factory: ArchiveConnectorServiceFactory creates backend-specific connectors.
• Metadata/data persistence: JPA repositories for document mapping and sync state.
• Scheduling: sync job and cache eviction schedulers.
• Security helpers: JWT validation service and optional certificate refresh flow.

Supported connector backends (ArchiveType):

• OPENTEXT
• EXTERNAL_FILE_SYSTEM
• FILE_ARCHIVE_SYSTEM
• SHAREPOINT
• SHAREPOINT_GRAPH
• ONEDRIVE
• AZURE_BLOB
• DOCUWARE

Request flow (typical):

1. API receives document operation + metadata.
2. Category mapping resolves target archive.
3. JWT/auth checks run (when enabled).
4. Request is executed on target connector.
5. On primary failure, optional failover/pipeline path is used.
6. DB mapping is updated (if enabled) to maintain stable document IDs.

4. API Surface

Main endpoint groups:

Domain	Base Path	Purpose
Health	/ping	Liveness probe
Create/update/find	/api/document/create, /api/document/update, /api/document/find	Document create/replace/find
Versioning and content	/api/document/{id}/upload/version, /api/document/{id}/download	Version upload and content retrieval
Base64 variants	/api/document/create/base64, /api/document/{id}/download/base64	Binary transport in base64 workflows
Metadata and object info	/api/document/{documentId}/info/latest, /api/document/{documentId}/object-info, /api/document/{documentId}/archive-info	Metadata/object/archive inspection
Deletion	/api/document/{id}	Document delete
Search v2	/api/v2/document/search, /api/v2/document/search/report	Structured search and report-based search
External auth	/api/v2/auth/{archiveName}	Connector-specific auth bootstrap
Configured custom requests	/api/archiverequest/{requestname}	Execute configured archive request mapping
Synchronisation control	/api/synchronisation/run	Trigger manual sync run
Category info	/api/archiveservice/documenttypes	Expose configured document type categories

Notes:

• OpenAPI annotations are present on main controllers.
• v2 endpoints focus on richer info/search/auth use cases.

5. Configuration Model

Core runtime properties in src/main/resources/application.yml:

Category	Key Prefix	What It Controls
Service identity	server.port (default 8090)	HTTP port
Database and schema	spring.datasource.*, spring.jpa.*, spring.liquibase.*	Metadata DB + migrations
Archive routing	archive-connections.*	Backend list, priority, failover, auth providers
Category mapping	opentext.transformSpecJsonPath.*, request/category JSON files	documentType -> archive routing and metadata transformations
Global archive behavior	archive-general-settings.*	DB mode, delete behavior, external ID strategy
Security/JWT	authentication.*, auth-providers.*	Token handling and access checks
Sync/failover	synchronisation.*	Retry, cron, hash check mode, enable/disable
MIME handling	fileMimeTypesAndExtensions	Content-type and extension resolution
Request logging	logRequests*	Request logging behavior
CORS	cors.*	Cross-origin settings
Metrics/tracing	management.*, service-data-collector.*	Actuator/metrics/tracing behavior

6. Security Model

• HTTP security config is profile-aware; default configuration (!jwtSecurity) permits API paths at filter-chain level.
• Business-layer security is enforced in ArchiveService through JwtAuthService before connector operations when JWT mode is enabled.
• Optional owner validation can restrict access to documents based on JWT claim ownership.
• Connector-level authentication is backend-specific (e.g., OpenText ticket/basic, Graph credentials, etc.).

Operational implication:

• Security correctness depends on both ingress controls and correct authentication.*/connector auth configuration.

7. Data and State

Document identity model:

• External archive document ID and DMSS-facing ID can differ.
• ID strategy (archive-general-settings.externalIdType): SEQUENCE, UID, UNMODIFIED, PREFIX.

Persistent state:

• DocumentInfo repository stores archive mapping, fallback/sync metadata, owner info, retry counters.
• DB can be enabled/disabled by configuration.

Failover and synchronization:

• If primary write fails and failover exists, document can be stored in fallback archive.
• Sync job later moves documents/versions to target archive and updates mapping.
• Hash-compare strategy (synchronisation.checkHash) can verify integrity during writes.

8. Integrations

Primary integration types:

• OpenText Content Server
• SharePoint (classic and Graph)
• OneDrive
• Azure Blob Storage
• DocuWare
• External filesystem/file-archive services

Integration behavior highlights:

• Connector factory instantiates connector implementation based on archiveType.
• Request mapping endpoint allows configured backend-specific requests.
• External auth endpoint exposes connector auth bootstrapping where supported.

9. Build, Run, Deploy

Technology baseline:

• Java 21
• Spring Boot
• Gradle wrapper

Container image:

• Available on Docker Hub: trustlynx/dmss-archive-services
• Image page: https://hub.docker.com/r/trustlynx/dmss-archive-services
• Image download/pull URL: docker.io/trustlynx/dmss-archive-services
• Pull command: docker pull trustlynx/dmss-archive-services

Build:

./gradlew clean build

Run (example):

java -jar build/libs/dmss-archive-services.jar --spring.config.location=/path/to/application.yml

Deployment notes:

• Liquibase requires DB connectivity when DB mode is enabled.
• Archive connector credentials/endpoints must be fully configured per environment.
• Keep request/category JSON mapping files synchronized with archive metadata model.

10. Operations and Troubleshooting

Health/ops endpoints:

• /ping returns pong.
• Actuator endpoints are configurable; health/prometheus are exposed by default in current config.

Scheduled jobs:

• Synchronization job via synchronisation.cron.
• Cache eviction (AUTHTOKENS) every 10 minutes.

Common failure points:

• Category mapping missing for a documentType (DocumentMappingException).
• Connector auth/config mismatch (401/403/5xx from backend).
• ID strategy mismatch after configuration changes.
• Failover loop or retry accumulation when both primary and failover are unavailable.
• Metadata transformation mismatch for backend-specific schemas.

11. Non-Goals and Boundary Decisions

• This service provides storage abstraction, not signing workflows.
• It intentionally centralizes archive connector complexity so other DMSS services interact with a stable API.
• Reliability strategy is implemented through failover + scheduled synchronization rather than transactional cross-backend writes.